Add Spin adapter by ChristianPavilonis · Pull Request #166 · stackpop/edgezero

ChristianPavilonis · 2026-02-18T16:56:30Z

Summary

Adds a new edgezero-adapter-spin crate that bridges Spin HTTP components into the EdgeZero router, following the established adapter pattern (Fastly, Cloudflare).

New crate: crates/edgezero-adapter-spin/ with context, request, response, proxy, and CLI modules
Scaffold support: Handlebars templates for cargo edgezero new --adapter spin scaffolding
Example adapter: examples/app-demo/crates/app-demo-adapter-spin/ reference implementation
Consistent API: init_logger(), AppExt trait, run_app() convenience entry point — matching Fastly/Cloudflare adapters

What's Included

Module	Description
`context.rs`	`SpinRequestContext` — extracts `spin-client-addr` and `spin-full-url` headers
`request.rs`	Converts `spin_sdk::http::IncomingRequest` → core `Request` with proper WASI resource handle management
`response.rs`	Converts core `Response` → `spin_sdk::http::Response` (buffered + streaming bodies)
`proxy.rs`	`SpinProxyClient` using `spin_sdk::http::send` for outbound HTTP
`cli.rs`	Build (`cargo build --target wasm32-wasip1`), deploy (`spin deploy`), serve (`spin up`) commands
`lib.rs`	`init_logger()`, `AppExt` trait, `run_app()` entry point

What's Not Included (Future Work)

KV store support

Testing

cargo fmt --all -- --check — clean
cargo clippy --workspace --all-targets --all-features -- -D warnings — clean
cargo test --workspace --all-targets — all tests pass (6 Spin adapter tests including context unit tests)
cargo check --workspace --all-targets --features "fastly cloudflare" — clean
Contract tests in tests/contract.rs (gated behind spin + wasm32, follows Fastly/Cloudflare pattern)
Deployed mocktioneer to Fermyon

- Fix cargo fmt formatting issues - Return EdgeError for unsupported HTTP methods instead of silently defaulting to GET - Add init_logger() matching Cloudflare's no-op pattern, call in run_app - Expose SpinRequestContext unconditionally (pure Rust, no WASM deps) - Add AppExt trait on App for consistent adapter API - Add contract test scaffold and context unit tests - Replace bare .unwrap() with .expect() in proxy header insert - Simplify anyhow wrapping in proxy error path to format!()

aram356

PR Review

Summary

Solid adapter implementation that follows the established Fastly/Cloudflare pattern well. However, the adapter does not compile for its actual wasm32-wasip1 target, and the scaffolding pipeline produces broken projects due to missing workspace deps and unresolved template variables. These must be fixed before merge.

😃 Praise

CLI scaffolding is thorough and well-tested — build/deploy/serve, blueprint registration, ctor auto-registration, manifest discovery with distance-based sorting, and 4 solid unit tests
Context module is correctly ungated from target_arch so it works in native tests
Method conversion (into_core_method) handles Method::Other with proper error reporting — more robust than the Fastly adapter

Findings

Blocking

🔧 wasm32 compile error: EdgeError::internal(format!(...)) — String doesn't impl Into<anyhow::Error> (proxy.rs:48)
🔧 Scaffold {crate_name} placeholder not replaced: generator only handles {crate} / {crate_dir} (cli.rs:178)
🔧 proj_spin_underscored template var never populated: renders as empty → broken spin.toml source path (spin.toml.hbs:12)
🔧 Generated projects fail: spin-sdk missing from seed_workspace_dependencies() in generator.rs:109
🔧 AppExt duplicates dispatch() logic: should delegate like Cloudflare/Fastly (lib.rs:42-56)
🔧 Zero contract test cases: build_test_app() exists but no #[test] functions (tests/contract.rs)
🔧 CI feature check missing spin: .github/workflows/test.yml:59 only checks fastly cloudflare

Non-blocking

🤔 Silent header drops in proxy.rs and response.rs: non-UTF-8/invalid headers discarded with no logging
🤔 client_addr stored as raw String: Fastly uses typed Option<IpAddr> — cross-adapter inconsistency
♻️ init_logger() identical cfg branches: both return Ok(()), gate adds no value
♻️ Body stream collection duplicated: identical Body::Stream → Vec<u8> in proxy.rs and response.rs
⛏ Template duplicate dependency: edgezero-adapter-spin in both [dependencies] and [target.wasm32.dependencies]

📌 Out of Scope

🌱 No compression/decompression in proxy: Fastly transparently decompresses gzip/brotli upstream responses. Spin passes compressed bytes through raw. Worth tracking for parity.
📌 CLAUDE.md not updated: workspace layout, compilation targets, CI features all omit Spin.

CI Status

fmt: PASS
clippy: PASS
tests: PASS (native)
feature check (fastly cloudflare): PASS
wasm32-wasip1 compile: FAIL (cargo check -p edgezero-adapter-spin --target wasm32-wasip1 --features spin)

crates/edgezero-adapter-spin/src/proxy.rs

crates/edgezero-adapter-spin/src/cli.rs

crates/edgezero-adapter-spin/src/templates/spin.toml.hbs

crates/edgezero-adapter-spin/src/lib.rs

crates/edgezero-adapter-spin/tests/contract.rs

crates/edgezero-adapter-spin/src/context.rs

crates/edgezero-adapter-spin/src/lib.rs

crates/edgezero-adapter-spin/src/response.rs

crates/edgezero-adapter-spin/src/templates/Cargo.toml.hbs

crates/edgezero-adapter-spin/src/cli.rs

prk-Jr

Can we update the documentation and readme.

- Fix wasm32 compile error: format!() -> anyhow::anyhow!() in proxy.rs - Fix scaffold {crate_name} -> {crate} placeholder in Spin build command - Add proj_{id}_underscored template var for spin.toml wasm filename - Add spin-sdk to seed_workspace_dependencies for generated projects - Delegate AppExt::dispatch to request::dispatch (matches CF pattern) - Change dispatch() return to concrete spin_sdk::http::Response type - Parse client_addr as Option<IpAddr> instead of Option<String> - Extract shared collect_body_bytes helper to deduplicate proxy/response - Add log::warn for silently dropped non-UTF-8 headers - Simplify init_logger by removing redundant cfg gates - Add contract tests (2 native, 3 wasm32-gated) with proper cfg split - Add spin to CI feature check and wasm32-wasip1 compilation step - Update CLAUDE.md and README.md with Spin adapter documentation

ChristianPavilonis · 2026-03-06T16:08:59Z

Review Fixes — Summary

All blocking and non-blocking findings from @aram356's review have been addressed in commit 7c2a2f9.

Blocking Fixes

Finding	Resolution
wasm32 compile error (`proxy.rs:48`)	`format!(...)` → `anyhow::anyhow!(...)` — `String` doesn't impl `Into<anyhow::Error>`
`{crate_name}` placeholder not replaced (`cli.rs:178`)	Changed to `{crate}` to match what the generator replaces (consistent with Axum adapter)
`proj_spin_underscored` never populated (`spin.toml.hbs:12`)	Generator now emits `proj_{id}_underscored` data entry with hyphens replaced by underscores
`spin-sdk` missing from `seed_workspace_dependencies` (`generator.rs`)	Added `spin-sdk = { version = "5.2", default-features = false }`
`AppExt` duplicates `dispatch()` logic (`lib.rs:42-56`)	Delegates to `request::dispatch()` now, matching the Cloudflare adapter pattern. Also changed `dispatch()` return type from `impl IntoResponse` to concrete `spin_sdk::http::Response` to make the delegation work.
Zero contract test cases (`tests/contract.rs`)	Added 5 tests: 2 run natively (`context_default_is_empty`, `build_test_app_creates_valid_router`), 3 gated behind wasm32 (`from_core_response` status/headers, streaming body, empty body). The native/wasm split ensures we get actual CI coverage for the tests that don't need the Spin runtime.
CI feature check missing `spin` (`.github/workflows/test.yml`)	Added `spin` to the feature string and added a dedicated `cargo check -p edgezero-adapter-spin --target wasm32-wasip1 --features spin` step

Non-blocking Fixes

Finding	Resolution
Silent header drops (`proxy.rs`, `response.rs`, `request.rs`)	Added `log::warn!` when headers are skipped due to non-UTF-8 values or invalid names
`client_addr` as raw `String` (`context.rs`)	Changed to `Option<IpAddr>`, added `parse_client_addr()` that handles `ip:port`, bare IP, and IPv6 bracket notation (with 5 unit tests)
`init_logger()` identical cfg branches (`lib.rs`)	Removed redundant cfg gates, single unconditional function
Body stream collection duplicated (`proxy.rs`, `response.rs`)	Extracted `collect_body_bytes(body: Body) -> Result<Vec<u8>, EdgeError>` as a `pub(crate)` helper in `response.rs`, used by both modules

Documentation

Updated CLAUDE.md and README.md to include the Spin adapter in workspace layout, compilation targets, feature gates, CI gates, proxy clients, and logging init references.

Verification

cargo fmt --all -- --check ✓
cargo clippy --workspace --all-targets --all-features -- -D warnings ✓
cargo test --workspace --all-targets — all pass (2 new native contract tests running)
cargo check --workspace --all-targets --features "fastly cloudflare spin" ✓
cargo check -p edgezero-adapter-spin --target wasm32-wasip1 --features spin ✓

@prk-Jr — documentation and README have been updated with Spin adapter info as requested.

aram356

Follow-up review — critical pathing bugs

The previous review addressed compile errors and code-quality issues. This review focuses on two runtime-breaking bugs that cause edgezero-cli build --adapter spin to fail on any hyphenated crate name or workspace member. Both are reproducible in the examples/app-demo demo.

Summary of findings

Sev	Issue	Impact
High	Artifact lookup uses raw package name (hyphens) but Cargo emits underscores	`build --adapter spin` exits with "compiled artifact not found" for any hyphenated crate
High	`spin.toml` `source` path points to crate-local `target/`, but workspace builds emit to workspace `target/`	`spin up` fails to find the wasm binary for any workspace member
Medium	`find_workspace_root` climbs to the topmost `Cargo.toml`, overshooting nested workspaces like `examples/app-demo/`	Build/deploy commands may search the wrong tree
Medium	Non-UTF-8 headers silently dropped across request/response/proxy boundaries	Breaks binary headers (signatures, auth tokens) in proxy edge cases
Medium	Test suite only exercises simple (non-hyphenated, flat workspace) artifact lookup — misses both regressions above	False green on CI

crates/edgezero-adapter-spin/src/cli.rs

crates/edgezero-adapter-spin/src/templates/spin.toml.hbs

crates/edgezero-adapter-spin/src/request.rs

crates/edgezero-adapter-spin/src/cli.rs

Fix artifact lookup hyphen-to-underscore bug in all three adapter CLIs, stop find_workspace_root at [workspace] tables for nested workspaces, compute correct target dir in spin.toml template for workspace members, and use HeaderValue::from_bytes for inbound request/proxy headers. Adds tests for hyphenated crate names and nested workspace resolution.

ChristianPavilonis · 2026-03-12T18:21:56Z

Review Fixes — Follow-up Review (Mar 11)

All findings from @aram356's follow-up review addressed in commit e9f4548.

File	Change
`crates/edgezero-adapter-spin/src/cli.rs`	Fix `locate_artifact` to use `crate_name.replace('-', "_")` for .wasm filename; fix `dest` copy target; add `locate_artifact_converts_hyphens_to_underscores` test
`crates/edgezero-adapter-fastly/src/cli.rs`	Same hyphen→underscore fix for `locate_artifact` and `dest`
`crates/edgezero-adapter-cloudflare/src/cli.rs`	Same hyphen→underscore fix for `locate_artifact` and `dest`
`crates/edgezero-adapter/src/cli_support.rs`	`find_workspace_root` now stops at `[workspace]` tables; add `workspace_root_stops_at_workspace_table` test
`crates/edgezero-adapter-spin/src/request.rs`	Use `HeaderValue::from_bytes(value)` to preserve non-UTF-8 inbound headers
`crates/edgezero-adapter-spin/src/proxy.rs`	Use `HeaderValue::from_bytes` for proxy response headers; document WASI limitation on outbound
`crates/edgezero-adapter-spin/src/response.rs`	Document WASI limitation for outbound non-UTF-8 headers
`crates/edgezero-adapter-spin/src/templates/spin.toml.hbs`	Use `{{target_dir_spin}}` for correct workspace-relative source path
`crates/edgezero-cli/src/generator.rs`	Compute `target_dir_{id}` template variable from crate depth
`examples/app-demo/.../spin.toml`	Fix source path to `../../target/...`

Verification

cargo fmt --all -- --check ✓
cargo clippy --workspace --all-targets --all-features -- -D warnings ✓
cargo test --workspace --all-targets — 323 tests pass ✓
cargo check --workspace --all-targets --features "fastly cloudflare spin" ✓

aram356

PR Review

Summary

Solid Spin adapter implementation that closely follows the established Fastly/Cloudflare patterns. Two blocking issues around proxy compression handling and logger gating need to be addressed before merge.

Findings

Blocking

🔧 Proxy client missing compression/decompression: The Spin proxy passes upstream compressed responses through verbatim, breaking the adapter contract (proxy.rs:62)
🔧 init_logger() missing dual feature-gate definitions: Diverges from Fastly/Cloudflare pattern; blocks future real logger integration (lib.rs:32)
❓ run_app calls init_logger() on every request: In Spin's per-request model, this will panic once a real logger is wired in (lib.rs:67)

Non-blocking

🤔 README claims "Stable" for untested adapter: Consider "Beta" or "Preview" until production-validated
🌱 collect_body_bytes has no size limit: Unbounded Vec growth; pre-existing cross-adapter concern
🏕 Contract tests don't exercise routing on host: Host-side tests are smoke tests only; consider dispatching through oneshot()
⛏ Example spin.toml hardcoded relative artifact path: Breaks silently if crate is moved

CI Status

fmt: PASS
clippy: PASS
tests: PASS (259 tests)

crates/edgezero-adapter-spin/src/proxy.rs

crates/edgezero-adapter-spin/src/lib.rs

crates/edgezero-adapter-spin/src/response.rs

crates/edgezero-adapter-spin/tests/contract.rs

examples/app-demo/crates/app-demo-adapter-spin/spin.toml

- Add compression/decompression handling in proxy.rs matching Fastly/Cloudflare adapter contract (gzip/brotli detection, header stripping) - Add dual cfg feature-gate to init_logger() matching Cloudflare/Fastly pattern - Change init_logger().expect() to let _ = init_logger() to prevent per-request panic in Spin's #[http_component] model - Add 3 host-side routing dispatch tests to contract.rs (GET, POST, streaming) exercising router via oneshot() - Change README Spin status from Stable to Preview

prk-Jr

PR Review

Summary

Adds the Fermyon Spin adapter (edgezero-adapter-spin) with full request/response conversion, proxy support with synchronous decompression, CLI scaffolding, and WASM-compatible contract tests. The implementation is structurally sound and follows project conventions closely, but two blocking issues must be resolved before merge: an unbounded decompressed body allocation in the proxy that creates a zip-bomb risk, and missing scaffold test assertions for the newly unconditional spin registration.

😃 Praise

Synchronous decompression rationale is well-documented (proxy.rs:97-102) — the comment explaining why async decompression is avoided in WASI's single-threaded executor is exactly the context future contributors need.
let _ = init_logger() with explanatory comment (lib.rs:77) — correctly handles the per-request invocation model where set_logger errors after the first call; silent discard is the right defensive pattern here.
Clean cfg gating throughout — the split between SpinRequestContext (always available) and WASM-gated proxy/request/response modules is precise and follows project conventions.
HeaderValue::from_bytes for inbound headers (request.rs:33-40) — correctly handles non-UTF-8 header values with a log::warn on drop, mirroring the Cloudflare adapter pattern from prior review feedback.

Findings

Blocking

🔧 Zip-bomb risk: decompress_body() has no output size cap — a 16 MiB gzip payload can expand to >1 GB. (proxy.rs:103-123)
❓ Missing scaffold test assertions for spin: generate_new_scaffolds_workspace_layout checks for cloudflare and fastly but not spin — the test would pass silently if spin scaffolding broke.
❓ Inbound request body has no adapter-level size cap: asymmetry with outbound bodies (16 MiB cap) is undocumented. (request.rs:50-53)

Non-blocking

🤔 Spin dep in both [dependencies] and [target.wasm32.dependencies]: Cargo merges features, activating the spin feature on native builds too. Consistent with the Cloudflare template — confirm intentional. (Cargo.toml.hbs:17,21)
♻️ Duplicate read_package_prefers_package_table test: verbatim copy already covered in cli_support.rs — remove. (cli.rs:316-323)
🏕 Scaffold test incomplete now that spin is always registered: 3 assert! lines would prevent future regressions.
⛏ "x-edgezero-proxy" is a bare string literal: repeated across adapters — a shared constant in edgezero-core would prevent typos. (proxy.rs:88-90)

📌 Out of Scope

locate_artifact is structurally duplicated across all three adapter CLI modules. Should be extracted to cli_support.rs with a target_triple parameter in a follow-up.
brotli and flate2 are unconditional deps not gated behind the spin feature, so they compile into edgezero-cli even though only used in WASM-gated modules. Consistent with other adapters — worth addressing if binary size becomes a concern.

CI Status

fmt: PASS
clippy: FAIL (pre-existing lint in edgezero-macros, not introduced by this PR)
tests: PASS (329 tests)

crates/edgezero-adapter-spin/src/proxy.rs

crates/edgezero-cli/src/generator.rs

crates/edgezero-adapter-spin/src/request.rs

crates/edgezero-adapter-spin/src/cli.rs

crates/edgezero-adapter-spin/src/proxy.rs

…roxy header constant - Add MAX_DECOMPRESSED_SIZE (64 MiB) limit with .take() guard in decompress_body() to prevent zip-bomb memory exhaustion - Add spin scaffold assertions to generate_new_scaffolds_workspace_layout test (workspace Cargo.toml, edgezero.toml, spin.toml) - Document inbound body size delegation to Spin runtime in request.rs - Remove duplicate read_package_prefers_package_table test from cli.rs (already covered in cli_support.rs) - Extract PROXY_HEADER constant to edgezero_core::proxy and update all three adapters (Spin, Fastly, Cloudflare) to use it

Extract decompress_body into ungated decompress module so unit tests (identity, gzip, brotli, zip-bomb) run on the host without wasm32. Add body content assertion to streaming contract test. Document the MAX_BODY_SIZE vs MAX_DECOMPRESSED_SIZE relationship. Use HeaderValue::from_str instead of from_bytes for string values. Add TODO marker for init_logger and clarifying comments to scaffold template and example spin.toml.

aram356

👍 Should be good to go once tests are fixed

aram356

@ChristianPavilonis Please resolve conflict

aram356 assigned ChristianPavilonis Feb 20, 2026

ChristianPavilonis added 2 commits March 4, 2026 11:05

initial spin implementation

f7855ef

ChristianPavilonis force-pushed the feature/spin branch from 705d6fe to 58aa63c Compare March 5, 2026 00:35

ChristianPavilonis changed the title ~~Support for spin framework~~ Add Spin (Fermyon) adapter Mar 5, 2026

ChristianPavilonis changed the title ~~Add Spin (Fermyon) adapter~~ Add Spin adapter Mar 5, 2026

ChristianPavilonis requested review from aram356 and prk-Jr March 5, 2026 00:42

ChristianPavilonis marked this pull request as ready for review March 5, 2026 00:42

aram356 requested changes Mar 6, 2026

View reviewed changes

prk-Jr reviewed Mar 6, 2026

View reviewed changes

ChristianPavilonis requested review from aram356 and prk-Jr March 6, 2026 16:12

Merge branch 'main' into feature/spin

5da0294

aram356 requested changes Mar 11, 2026

View reviewed changes

aram356 linked an issue Mar 12, 2026 that may be closed by this pull request

Spin Adapter #68

Open

ChristianPavilonis requested a review from aram356 March 12, 2026 18:14

aram356 requested changes Mar 14, 2026

View reviewed changes

ChristianPavilonis requested a review from aram356 March 16, 2026 20:57

Fix review findings: sync decompression, body size cap, docs

082428d

prk-Jr requested changes Mar 17, 2026

View reviewed changes

ChristianPavilonis requested a review from prk-Jr March 17, 2026 16:31

aram356 approved these changes Mar 18, 2026

View reviewed changes

aram356 requested changes Mar 20, 2026

View reviewed changes

Conversation

ChristianPavilonis commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's Included

What's Not Included (Future Work)

Testing

Uh oh!

aram356 left a comment

Choose a reason for hiding this comment

PR Review

Summary

😃 Praise

Findings

Blocking

Non-blocking

📌 Out of Scope

CI Status

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

prk-Jr left a comment

Choose a reason for hiding this comment

Uh oh!

ChristianPavilonis commented Mar 6, 2026

Review Fixes — Summary

Blocking Fixes

Non-blocking Fixes

Documentation

Verification

Uh oh!

aram356 left a comment

Choose a reason for hiding this comment

Follow-up review — critical pathing bugs

Summary of findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ChristianPavilonis commented Mar 12, 2026

Review Fixes — Follow-up Review (Mar 11)

Verification

Uh oh!

aram356 left a comment

Choose a reason for hiding this comment

PR Review

Summary

Findings

Blocking

Non-blocking

CI Status

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

prk-Jr left a comment

Choose a reason for hiding this comment

PR Review

Summary

😃 Praise

Findings

Blocking

Non-blocking

📌 Out of Scope

CI Status

Uh oh!

Uh oh!

ChristianPavilonis commented Feb 18, 2026 •

edited

Loading